home *** CD-ROM | disk | FTP | other *** search
/ Magnum One / Magnum One (Mid-American Digital) (Disc Manufacturing).iso / d21 / qw12add.arc / XDI.TEC < prev   
Text File  |  1990-12-19  |  9KB  |  159 lines
  1. ID:XD XDI Specification for DESQview
  2. Quarterdeck Technical Note
  3. by Daniel Travison
  4.  
  5. Q: How can my device driver/TSR work better with DESQview?
  6.  
  7. DESQview's External Device Interface
  8.  
  9. DESQview version 2.26 (and above), can issue informative messages to third
  10. party software in order for that software to monitor certain DESQview
  11. operations such as starting a task or swapping out a process. These
  12. messages can be useful for determining when to allocate/deallocate
  13. resources (e.g., memory) on a process by process basis, communicating with
  14. tasks running within DESQview, rescheduling tasks, tracking DESQview's task
  15. switching, etc.
  16.  
  17. DESQview provides this information through the External Device Interface
  18. (XDI) - Quarterdeck's specification for communicating with external
  19. drivers.
  20.  
  21. An XDI driver may be implemented either as a DOS device driver (loaded by
  22. CONFIG.SYS), a Terminate and Stay Resident program (TSR) loaded before or
  23. after DESQview, or as a DESQview shared program (shared among several
  24. processes).  For the rest of this documentation, the term 'driver' will
  25. normally refer to a program that uses the XDI irrespective of its method of
  26. implementation (device driver, TSR or shared program).  Also, any number of
  27. XDI drivers can be loaded.  When DESQview starts, it simply attaches itself
  28. to the XDI chain and starts sending XDI messages to to previously loaded
  29. XDI drivers.
  30.  
  31. Within the XDI, there are 15 subfunctions (messages). Fourteen of these
  32. messages inform the driver what action DESQview has just performed or
  33. is about to perform.  Your driver can choose to ignore the message and pass
  34. it on to the next driver in the chain, perform/schedule work based on the
  35. message, or save information for later use (e.g., the current mapping
  36. context).
  37.  
  38.       XDI_CHECK_PRESENCE      Check for XDI driver presence
  39.       XDI_RESERVED_SUBFUNC    XDI driver custom subfunction
  40.       XDI_START_DV            DV system initialization complete
  41.       XDI_END_DV              DV system termination
  42.       XDI_START_PROC          DV process creation
  43.       XDI_END_PROC            DV process termination
  44.       XDI_START_TASK          Task creation
  45.       XDI_END_TASK            Task termination
  46.       XDI_SAVE_STATE          Task state save
  47.       XDI_RESTORE_STATE       Task state restore
  48.       XDI_KEYBOARD            Change of keyboard focus
  49.       XDI_PROCESS_DVP         Processing of DVP file complete
  50.       XDI_SWAPPING_OUT        Swap out of DV process
  51.       XDI_SWAPPED_IN          Swap in of DV process
  52.       XDI_FAILED_DVP          DV process creation failure
  53.  
  54. An XDI driver can schedule second level handlers to make API calls, collect
  55. data, transfer data, dispatch tasks, perform initialization/termination
  56. when DESQview is started and quit.
  57.  
  58. The fifteenth subfunction, XDI_RESERVED_SUBFUNC provides a method for
  59. applications to communicate with your driver without needing to grab an
  60. additional interrupt vector.  Additionally, this interface does not require
  61. DESQview to be loaded.  In other words, if DESQview is not loaded, the
  62. application and XDI driver will still be able to communicate.
  63.  
  64. Q: When would I want to use the XDI specification?
  65.  
  66. If your driver needs to write into an application's address space then you
  67. need to ensure that the address is valid when you perform the write. (e.g.,
  68. The DOS SETDTA call requires the caller provide a pointer to a buffer that
  69. will be filled in at a later time.  A communications handler might use a
  70. similar interface but perform the update at interrupt time.)  With
  71. DESQview, this buffer may get mapped in and out to accomodate running
  72. multiple programs. If your driver attempts to write into this buffer when
  73. DESQview has mapped some other application into it (e.g., at interrupt
  74. time) then you will be corrupting the unknown application. The XDI allows
  75. your driver to determine when the write operation is safe or specifically
  76. request that DESQview map the application in to allow safe access to the
  77. application's address space.
  78.  
  79. Another example is the use of Multiplex boards.  Multiplex boards have two
  80. important features: One, they provide access to multiple external devices
  81. (e.g., modems) using a single IRQ and two, they provide a software
  82. interface for applications.  The software interface removes the need for
  83. the application to manage the hardware directly.  In the case of a
  84. multiplex board providing additional serial ports, the user will often want
  85. to run more than one program at a time to take advantage extra serial
  86. ports. (e.g., A number of BBS systems provide the option for running
  87. multiple copies at once and also support drivers for multiplex boards.)
  88. The programmer writing the driver will need to accomodate simultaneous
  89. access to the driver as well as provide a reliable software interface.
  90.  
  91. Other issues addressed by the XDI:
  92.  
  93.    1) Allocation of a software interrupt to allow the application to
  94.       communicate with the driver.  With more and more device drivers and
  95.       TSR's available, it is important to prevent possible conflicts with
  96.       other software. The XDI specification uses the multiplex interrupt
  97.       (INT 2Fh) as a basis for sharing a single interrupt using a well
  98.       defined interface.  Once the application has 'logged' itself with the
  99.       driver (XDI_RESERVED_SUBFUNC), the driver might provide an ID for
  100.       future use or simply manage it internally based on which process
  101.       DESQview has mapped in when the software interrupt is called.  This
  102.       portion of the interface functions in the same manner whether
  103.       DESQview is loaded or not.  When DESQview is not present, the driver
  104.       does not need to be concerned with the mapping context.
  105.  
  106.    2) Allocation of memory/application that needs to be accessible at any
  107.       given time.  This might be a buffer for incoming data.  Normally, the
  108.       driver would need to allocate all of its memory needs during its
  109.       initialization code.  DESQview allows an XDI driver to allocate
  110.       COMMON memory (memory that does not get mapped out) during an XDI
  111.       call.  This allows the driver to allocate only the memory necessary
  112.       when a new application starts.  It DESQview is not present, the
  113.       application would allocate a buffer out of its own data space. A
  114.       check for DESQview would be all that is necessary for the application
  115.       to determine whether it needs to allocate a buffer or allow the
  116.       driver to allocate it from COMMON memory.
  117.  
  118.    3) Preventing reentrancy during non-reentrant sections of code.  In a
  119.       perfect world, all of your driver's code would be reentrant.  Since
  120.       this may not be practical without unreasonble code or CPU overhead,
  121.       the XDI driver can temporarily suspend multitasking to perform its
  122.       critical work.  This does not mean that the XDI allows you to write
  123.       non-reentrant handlers but it can solve some sticky issues that arise
  124.       when you need to support simultaneous access.
  125.  
  126.    4) The application can not keep up with the data rate.  There will be
  127.       times when the application can not empty the driver's buffer faster
  128.       than the driver can fill it.  The user may have started up a few
  129.       extra applications and the CPU is too slow to give everyone enough
  130.       time. The XDI driver could consider some percentage of the buffer as
  131.       a threshold. When this threshold is reached the driver can
  132.       temporarily override DESQview's dispatcher and force the
  133.       application's 'buffer management' routine to execute at the next
  134.       context switch.
  135.  
  136.    5) The driver needs to know when the application exits to allow proper
  137.       cleanup.  Normally, the application itself would call the driver to
  138.       initiate cleanup.  Occasionally this will not occur (e.g., the user
  139.       shut down the application via DESQview's Close Window menu
  140.       selection).  DESQview notifies the XDI driver when a process ends to
  141.       allow the driver to determine if it needs to perform any cleanup for
  142.       the process.
  143.  
  144. There are other areas where an XDI driver would be of use; resource
  145. tracking on a process by process basis, modifying the .DVP when each
  146. process starts, allocating additional system memory for the process at
  147. startup, tracking CPU usage, or even displacing DESQview's dispatcher.
  148.  
  149. Q: How do I find out more about the XDI?
  150.  
  151. DESQview's XDI is fully documented in Quarterdeck's API Reference Manual
  152. (versions 1.20 and later).  Included is a sample XDI driver (POKEXDI.ASM)
  153. that can be used as a template for designing your own. Contact Quarterdeck
  154. for information on obtaining a copy of our API Reference Manual or upgrading
  155. and older API Reference Manual.
  156.  
  157.         Copyright (C) 1990 by Quarterdeck Office Systems
  158.              * * *   E N D   O F   F I L E    * * * 
  159.